home *** CD-ROM | disk | FTP | other *** search
/ Amiga Collections: Taifun / Taifun 175 (1991-09-10)(Manewaldt, A.)(DE)(PD).zip / Taifun 175 (1991-09-10)(Manewaldt, A.)(DE)(PD).adf / Term / Libs.LZH / xprkermit.doc < prev    next >
Text File  |  1991-07-26  |  11KB  |  258 lines
  1.                 XPR Kermit 
  2.                 Version 1.5 - RELEASE
  3.  
  4.                    Marco Papa - Felsina Software
  5.            Stephen R. Walton, Cal State Northridge
  6.  
  7. This is a beta version of an External Protocol (XPR) library for the Kermit
  8. file transfer protocol.  In keeping with the Kermit documents, here is a
  9. list of the items supported and not supported.
  10.  
  11. XPR Kermit Capabilities At A Glance:
  12.  
  13.   Local operation:                   Yes
  14.   Remote operation:                  No
  15.   Login scripts:                     *
  16.   Transfer text files:               Yes
  17.   Transfer binary files:             Yes
  18.   Wildcard send:                     Yes
  19.   File transfer interruption:        Yes
  20.   Filename collision avoidance:      No
  21.   Can time out:                      Yes
  22.   8th-bit prefixing:                 Yes
  23.   Repeat count prefixing:            Yes
  24.   Alternate block checks:            Yes
  25.   Terminal emulation:                *
  26.   Communication settings:            Yes
  27.   Transmit BREAK:                    *
  28.   Support for dialout modems:        *
  29.   IBM mainframe communication:       *
  30.   Transaction logging:               No
  31.   Session logging (raw download):    No
  32.   Debug logging:                     No
  33.   Packet logging:                    No
  34.   Act as server:                     No
  35.   Talk to server:                    Yes
  36.   Advanced server functions:         No
  37.   Local file management:             *
  38.   Command/Init files:                *
  39.   UUCP and multiuser line locking:   *
  40.   Long packets:                      Yes
  41.   Sliding Windows:                   No
  42.   File attributes packets:           No
  43.   Command macros:                    *
  44.   Raw file transmit:                 *
  45.  
  46. The items marked with a '*' above are those which are to be provided by the
  47. calling terminal emulation program.
  48.  
  49. I. Introduction
  50. ---------------
  51.  
  52. XPR Kermit implements the Kermit file transfer protocol in the form of an
  53. Amiga External Protocol (XPR) library.  This allows the addition of an
  54. up-to-date version of the Kermit protocol to any communications program
  55. which supports the XPR specification.  For further information on Kermit,
  56. read the book "Kermit:  A File Transfer Protocol" by Frank da Cruz, 1986,
  57. Digital Press.
  58.  
  59. To install XPR Kermit, simply copy the file "xprkermit.library" to your
  60. LIBS: directory, and request your comm program to use XPRKERMIT as its
  61. external file transfer protocol.
  62.  
  63. XPR Kermit supports Version 2.0 of the XPR Protocol specification.  For
  64. more details on this, I recommend that you find a copy of the XPR Zmodem
  65. library, version 2.0.  Its documentation contains a good deal of the
  66. justification and philosophy of external protocol libraries, which I
  67. won't repeat here.
  68.  
  69. II. Use
  70. -------
  71.  
  72. XPR Kermit supports the parts of the Kermit protocol outlined in the table
  73. above.  There are currently seven user-settable parameters in XPR Kermit,
  74. which cover the parameters which are most often necessary to customize.
  75. If your communications problem is especially severe--for example, your
  76. method of connection to another system swallows characters which are special
  77. to Kermit, such as '#' or '&'--you may need to get a copy of the stand-alone
  78. Kermit program, C Kermit for the Amiga, distributed via many paths.
  79.  
  80. There are actually two sets of "setup" parameters in XPR Kermit.  The first
  81. set are commands which XPR Kermit can send to a remote Kermit server. These
  82. are not actually setups, but are in fact commands to XPR Kermit which cause it
  83. to communicate with a remote Kermit server.  The fourth command in this group
  84. is "Change Options," which causes no communication.  Instead, you are
  85. requested for changes in the current values of the parameters which Kermit
  86. will use for communication.
  87.  
  88. These items can be set in one of two ways.  One method is with a simple
  89. character string which is sent to XPR Kermit by the comm program;  this string
  90. will hereafter be referred to as the "init string."  This is generally done if
  91. an environment variable named "xprkermit" exists and has a value, in which
  92. case XPR Kermit is sent the value when you first select XPR Kermit as your
  93. protocol.  Some comm programs also allow an initialization string to be sent
  94. in other ways, such as from a script; VLT, for example, has an INITXPR script
  95. command.  The format of this string is specified by the external protocol.
  96.  
  97. The second, more elegant method, is with some type of requester or set
  98. of requesters.  In this case, you will be presented by your comm program
  99. with a set of Intuition gadgets of some type which allow the choice of
  100. XPR Kermit commands and the setting of the options.
  101.  
  102. However, the string method has the advantage of giving one the ability to
  103. change external protocol settings non-interactively, such as from a script. 
  104. In the case of XPR Kermit, such a script can actually command XPR Kermit to
  105. perform communication.  One obvious use of this is to transfer an entire
  106. directory tree from your Amiga to a remote machine:  you can make the remote's
  107. Kermit a server and command it to perform the appropriate CD commands, then
  108. transfer files.
  109.  
  110. The currently supported XPR Kermit server commands are listed below.
  111. The format of the init string is in parentheses, generally simply a
  112. single letter.
  113.  
  114.     Kermit Finish (F):  Tells a Kermit server that you are done.  The
  115.     remote server will stop being a server.
  116.  
  117.     Kermit Bye (B):  Tells a Kermit server that you are done;  the server
  118.     will exit and log you off the remote machine.
  119.  
  120.     Kermit CD (C{dir}):  Change the default directory for files sent or
  121.     received by the Kermit server.  Examples of the init string would
  122.     be 'C/bin' or 'Cuser:[username.amiga]'.
  123.  
  124. For setting options via an init string, the first character of the init
  125. string must be the letter O (for Options).  Following that letter can
  126. be one or more of the option setting formats listed bellow;  these
  127. can be separated by whitespace and/or commas.
  128.  
  129. There are three settings which are either "yes" or "no."  Your comm program
  130. will give you some way of setting them interactively.  Simple button gadgets
  131. will be labeled "yes" and "no;"  otherwise, you may see a string gadget,
  132. into which you should type the word "yes" or "no" by hand.  This string is
  133. case-insensitive.  In the init-string, "yes" is represented by the single
  134. upper-case character Y.
  135.  
  136.     Convert FileName (C{Y|N}):  If "yes," then incoming file names are
  137.     converted to a form acceptable to the Amiga.  Currently, this
  138.     means simply translating them to lower case.  Default "yes."
  139.  
  140.     Host Server (G{Y|N}):  If "yes," then the host (remote) Kermit is
  141.     assumed to be in server mode.  You will be prompted for file
  142.     names when you request an XPR Kermit receive, and this file
  143.     name will be sent to the server in the form of a Kermit GET
  144.     command.  Default "no."
  145.  
  146.     Text File (T{Y|N}):  Flags whether the incoming file is text or binary.
  147.     If "yes," then carriage-return/line-feed pairs in the incoming
  148.     packets are converted to a single line-feed before writing the
  149.     packet to a file, and the opposite conversion is made when a file
  150.     is sent to a remote system.  Default "yes".
  151.  
  152.     If your communcations program supports its own text/binary flag
  153.     (that is, if the xpr_finfo() function exists and can tell XPR
  154.     Kermit whether a given file is text or binary), this option will
  155.     not appear.
  156.  
  157. Numerical settings are as follows.  Here, the init string key letter should
  158. be followed by a numerical value.
  159.  
  160.     Packet Length (P{length}):  The Long Packets extension to Kermit is
  161.     fully supported. Setting a packet length larger than 94 (the
  162.     default) enters long packet mode automatically.  If you use long
  163.     packets, it is *strongly* recommended that you use block check 2
  164.     or 3 (see below) if the host Kermit supports them. The current
  165.     limit is 1024 for XPR Kermit;  the default value is 94, the
  166.     longest standard Kermit packet.
  167.  
  168.     Block Check (B{type}):  This can have the value of 1, 2, or 3, and
  169.     chooses successively more stringent types of error checking on
  170.     the incoming data:  6-bit checksum, 12-bit checksum, and 16-bit
  171.     CRC, respectively.  Default is 1 (6-bit checksum).
  172.  
  173.     Timeout (O{seconds}):  The length of time XPR Kermit will wait for a
  174.     packet before assuming it isn't coming.  Default 5 seconds.  (The
  175.     O is for Out, as in TimeOut;  T is already taken by the Text flag.)
  176.  
  177.      Retry Limit (R{number}):  The number of times XPR Kermit will attempt
  178.     to send or receive the next packet of data before quitting.  Notice
  179.     that if the remote end simply stops sending, a length of time equal
  180.     to the retry limit times the timeout will elapse before XPR Kermit
  181.     actually exits.  Default 10 retries.
  182.  
  183. These can be mixed and matched.  For instance, to talk to a Kermit server
  184. with 750-byte packets, block check 2, binary files, and a 10-second timeout,
  185. the init string could be "OP750,B2,TN,O10".  Cryptic, but usable.
  186.  
  187. III. Future Extensions
  188. ----------------------
  189.  
  190. There are several items to be added to this XPR.  In rough order of priority,
  191. these are:
  192.  
  193. 1.  Delete on error.  XPR Kermit does not delete a partial file if there
  194. is an error on receive.
  195.  
  196. 2.  A better display of the status of the file transfer.
  197.  
  198. 3.  Re-entrancy.  If you are one of those lucky people with multiple serial
  199. ports on your Amiga, then XPR Kermit will only run on one of those ports
  200. at a time at present.
  201.  
  202. 4. Speed. The book's code does a great deal of work which could be done
  203. quite a bit more efficiently.  Many improvements are in the current
  204. version of C Kermit, Columbia's version 4F(095).
  205.  
  206. 5.  "Real" Kermit.  At some point, XPR Kermit will, I hope, become an
  207. interface to Columbia University's C Kermit code.  This will allow
  208. XPR Kermit to always contain the latest version of the Kermit protocol,
  209. provided that I or someone writes the new machine-dependent functions,
  210. if any.
  211.  
  212. Before embarking on any of the above improvements, I will be taking
  213. a break from this code.  When I get started again, the first order of
  214. business will be some code reorganization and a switch to version 5.0
  215. of Manx Aztec C.
  216.  
  217. IV.  Other information
  218. ----------------------
  219.  
  220. The file "kermitproto.doc" describes the code contained in the file
  221. "kermitproto.w," which actually implements the Kermit protocol.
  222.  
  223. V.  Credits
  224. -----------
  225.  
  226. The following people had a hand in this code.  In chronological order,
  227. they are:
  228.  
  229. -- Frank DaCruz of Columbia University, who wrote the original code and
  230.    published it in his book.
  231. -- Steve Walton of Cal State Northridge, who got Frank's code actually
  232.    working in the form of the original "kermitproto.w" module.
  233. -- Marco Papa of Felsina Software, for the first beta XPR version
  234. -- Steve Walton, for second and subsequent XPR Kermit's.
  235.  
  236. Other acknowledgements go to Willy Langeveld for developing the XPR
  237. spec, and to Rick Huebner, several of whose ideas in XPR Zmodem were
  238. taken over into XPR Kermit by Steve Walton. Thank you all! 
  239.  
  240. VI.  Gripes
  241. -----------
  242.  
  243. The current author and babysitter of this code is:
  244.     Stephen Walton
  245.     Department of Physics and Astronomy
  246.     Cal State Northridge
  247.     18111 Nordhoff St.
  248.     Northridge, CA 91330 USA
  249.     (818) 885-2775
  250.  
  251. E-mail can go to:
  252.     s_walton (BIX)
  253.     WALTON (PeopleLink)
  254.     ecphssrw@afws.csun.edu or swalton@solar.stanford.edu (Internet)
  255.  
  256. Thanks and congratulations gratefully accepted;  bug fixes and enhancements
  257. even more so!
  258.